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Preliminary Specification - Use with caution 



Introduction 



Cookies are a general mechanism which server side connections (such as CGI scripts) can use to both 
store and retrieve information on the client side of the connection. The addition of a simple, persistent, 
client-side state significantly extends the capabilities of Web-based client/server applications. 



A server, when returning an HTTP object to a client, may also send a piece of state information which 
the client will store. Included in that state object is a description of the range of URLs for which that 
state is valid. Any future HTTP requests made by the client which fall in that range will include a 
transmittal of the current value of the state object from the client back to the server. The state object is 
called a cookie, for no compelling reason. 

This simple mechanism provides a powerful new tool which enables a host of new types of applications 
to be written for web-based environments. Shopping applications can now store information about the 
currently selected items, for fee services can send back registration information and free the client from 
retyping a user-id on next connection, sites can store per-user preferences on the client, and have the 
client supply those preferences every time that site is connected to. 



A cookie is introduced to the client by including a Set-Cookie header as part of an HTTP response, 
typically this will be generated by a CGI script. 

Syntax of the Set-Cookie HTTP Response Header 

This is the format a CGI script would use to add to the HTTP headers a new piece of data which is to be 
stored by the client for later retrieval. 

Set-Cookie: NAME= VAL UE ; expire SEDATE; 
path-PATH; doma i n=DOMA I N_ NAME; secure 

NAME=VALUE 

This string is a sequence of characters excluding semi-colon, comma and white space. If there is a 
need to place such data in the name or value, some encoding method such as URL style %XX 
encoding is recommended, though no encoding is defined or required. 

This is the only required attribute on the Set-Cookie header. 

expires -DATE 

The expires attribute specifies a date string that defines the valid life time of that cookie. Once the 
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expiration date has been reached, the cookie will no longer be stored or given out. 
The date string is formatted as: 

Wdy, DD-Mon-YYYY HH:MM:SS GMT 

This is based on RFC 822, RFC 85 0 , RFC 103 6, a nd RFC 112 3, with the variations that the only 
legal time zone is GMT and the separators between the elements of the date must be dashes. 

expires is an optional attribute. If not specified, the cookie will expire when the user's session 
ends. 

Note: There is a bug in Netscape Navigator version 1.1 and earlier. Only cookies whose path 
attribute is set explicitly to 7" will be properly saved between sessions if they have an expires 
attribute. 

domain ^DOMAIN NAME 

When searching the cookie list for valid cookies, a comparison of the domain attributes of the 
cookie is made with the Internet domain name of the host from which the URL will be fetched. If 
there is a tail match, then the cookie will go through path matching to see if it should be sent. 
"Tail matching" means that domain attribute is matched against the tail of the fully qualified 
domain name of the host. A domain attribute of "acme.com" would match host names 
"anvil.acme.com" as well as "shipping.crate.acme.com". 

Only hosts within the specified domain can set a cookie for a domain and domains must have at 
least two (2) or three (3) periods in them to prevent domains of the form: ".com", ".edu", and 
"va.us". Any domain that fails within one of the seven special top level domains listed below only 
require two periods. Any other domain requires at least three. The seven special top level domains 
are: "COM", "EDU", "NET", "ORG", "GOV", "MIL", and "INT". 

The default value of domain is the host name of the server which generated the cookie response. 



The path attribute is used to specify the subset of URLs in a domain for which the cookie is valid. 
If a cookie has already passed domain matching, then the pathname component of the URL is 
compared with the path attribute, and if there is a match, the cookie is considered valid and is sent 
along with the URL request. The path 7foo" would match "/foobar" and "/foo/bar.html". The path 
"/" is the most general path. 

If the path is not specified, it as assumed to be the same path as the document being described by 
the header which contains the cookie. 

secure 

If a cookie is marked secure, it will only be transmitted if the communications channel with the 
host is a secure one. Currently this means that secure cookies will only be sent to HTTPS (HTTP 
over SSL) servers. 

If secure is not specified, a cookie is considered safe to be sent in the clear over unsecured 
channels. 

Syntax of the Cookie HTTP Request Header 

When requesting a URL from an HTTP server, the browser will match the URL against all cookies and 
if any of them match, a line containing the name/ value pairs of all matching cookies will be included in 
the HTTP request. Here is the format of that line: 

Cookie: NAME1 ^OPAQUE_ S TR ING1 ; NAME2=0PAQ UE_ S TR ING2 ... 
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Additional Notes 

• Multiple Set-Cookie headers can be issued in a single server response. 

• Instances of the same path and name will overwrite each other, with the latest instance taking 
precedence. Instances of the same path but different names will add additional mappings. 

• Setting the path to a higher-level value does not override other more specific path mappings. If 
there are multiple matches for a given cookie name, but with separate paths, all the matching 
cookies will be sent. (See examples below.) 

• The expires header lets the client know when it is safe to purge the mapping but the client is not 
required to do so. A client may also delete a cookie before it's expiration date arrives if the number 
of cookies exceeds its internal limits. 

• When sending cookies to a server, all cookies with a more specific path mapping should be sent 
before cookies with less specific path mappings. For example, a cookie "namel =foo" with a path 
mapping of 7" should be sent after a cookie "namel =foo2" with a path mapping of "/bar" if they 
are both to be sent. 

• There are limitations on the number of cookies that a client can store at any one time. This is a 
specificatipn of the minimum number of cookies that a client should be prepared to receive and 
store. 

o 300 total cookies 

o 4 kilobytes per cookie, where the name and the OPAQUE_STRING combine to form the 4 
kilobyte limit. 

o 20 cookies per server or domain, (note that completely specified hosts and domains are 
treated as separate entities and have a 20 cookie limitation for each, not combined) 
Servers should not expect clients to be able to exceed these limits. When the 300 cookie limit or 
the 20 cookie per server limit is exceeded, clients should delete the least recently used cookie. 
When a cookie larger than 4 kilobytes is encountered the cookie should be trimmed to fit, but the 
name should remain intact as long as it is less than 4 kilobytes. 

• If a CGI script wishes to delete a cookie, it can do so by returning a cookie with the same name, 
and an expires time which is in the past. The path and name must match exactly in order for the 
expiring cookie to replace the valid cookie. This requirement makes it difficult for anyone but the 
originator of a cookie to delete a cookie. 

• When caching HTTP, as a proxy server might do, the Set-cookie response header should never be 
cached. 

• If a proxy server receives a response which contains a Set-cookie header, it should propagate the 
Set-cookie header to the client, regardless of whether the response was 304 (Not Modified) or 200 
(OK). 

Similarly, if a client request contains a Cookie: header, it should be forwarded through a proxy, 
even if the conditional If-modified-since request is being made. 

Examples 

Here are some sample exchanges which are designed to illustrate the use of cookies. 
First Example transaction sequence: 

Client requests a document, and receives in the response: 
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Set-Cookie: CUSTOMER=WILE_E_COYOTE; path=7; expires=Wednesday, 09-Nov-99 23:12:4 

When client requests a URL in path 7" on this server, it sends: 

Cookie : CUSTOMER=WILE_E_COYOTE 

Client requests a document, and receives in the response: 

Set-Cookie : PART_NUMBER=ROCKET_LAUNCHER_0001 ; patrW 

When client requests a URL in path 7" on this server, it sends: 

Cookie: CUSTOMER=WILE_E_COYOTE; PART__NUMBER-ROCKET_LAUNCHER_0 001 

Client receives: 

Set-Cookie: SHIPPING=FEDEX; path=/foo 

When client requests a URL in path 7" on this server, it sends: 

Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001 

When client requests a URL in path 7foo" on this server, it sends: 

Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0 001; SHIPPING=FEDEX 

Second Example transaction sequence: 

Assume all mappings from above have been cleared. 
Client receives: 

Set-Cookie: PART__NUMBER=ROCKET__LAUNCHER_0 001; path*/ 

When client requests a URL in path 7" on this server, it sends: 

Cookie : PART_NUMBER=ROCKET_LAUNCHER_0001 

Client receives: 

Set-Cookie: PART_NUMBER=RI DI NG_ROCKET_0 023; path=/ammo 

When client requests a URL in path "/ammo" on this server, it sends: 

Cookie: PART_NUMBER=RIDING_ROCKET_0023 ; PART_NUMBER=ROCKET_LAUNCHER_0001 

NOTE: There are two name/ value pairs named "PART_NUMBER" due to the inheritance of the 
7" mapping in addition to the "/ammo" mapping. 
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